package com.che.software.testato.domain.dao;

import java.util.List;

import com.che.software.testato.domain.dao.jdbc.exception.IterationCreationDAOException;
import com.che.software.testato.domain.dao.jdbc.exception.IterationSearchDAOException;
import com.che.software.testato.domain.dao.jdbc.exception.IterationUpdateDAOException;
import com.che.software.testato.domain.entity.Iteration;
import com.che.software.testato.domain.entity.Prioritization;
import com.che.software.testato.domain.entity.Script;
import com.che.software.testato.domain.entity.search.IterationSearch;

/**
 * DAO interface dedicated to the iterations management.
 * 
 * @author Clement HELIOU (clement.heliou@che-software.com).
 * @copyright Che Software.
 * @license GNU General Public License.
 * @since July, 2011.
 * 
 *        This file is part of Testato.
 * 
 *        Testato is free software: you can redistribute it and/or modify it
 *        under the terms of the GNU General Public License as published by the
 *        Free Software Foundation, either version 3 of the License, or (at your
 *        option) any later version.
 * 
 *        Testato is distributed in the hope that it will be useful, but WITHOUT
 *        ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 *        FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 *        for more details.
 * 
 *        You should have received a copy of the GNU General Public License
 *        along with Testato. If not, see <http://www.gnu.org/licenses/>.
 * 
 *        Testato's logo is a creation of Arrioch
 *        (http://arrioch.deviantart.com/) and it's distributed under the terms
 *        of the Creative Commons License.
 */
public interface IIterationDAO {

	/**
	 * Creates the next iteration (both analytical and selective) for a given
	 * prioritization.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param prioritization the given prioritization.
	 * @param scripts the scripts to use.
	 * @since July, 2011.
	 * @throws IterationCreationDAOException if an error occurs during the
	 *         creation.
	 */
	public void createNextIteration(Prioritization prioritization, List<Script> scripts) throws IterationCreationDAOException;

	/**
	 * Retrieves the current iteration to process for a given prioritization.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param prioritization the given prioritization.
	 * @return the current iteration to process id.
	 * @since July, 2011.
	 * @throws IterationSearchDAOException if an error occurs during the search.
	 */
	public int getCurrentIterationFromPrioritization(Prioritization prioritization) throws IterationSearchDAOException;

	/**
	 * Retrieves the remaining scripts count for a given prioritization.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param prioritization the given prioritization.
	 * @return the resulting count.
	 * @since July, 2011.
	 * @throws IterationSearchDAOException if an error occurs during the search.
	 */
	public int getRemainingScriptsCountFromPrioritization(Prioritization prioritization) throws IterationSearchDAOException;

	/**
	 * Retrieves the scripts count for a given iteration.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param iterationId the given iteration id.
	 * @return the resulting scripts count.
	 * @since July, 2011.
	 * @throws IterationSearchDAOException if an error occurs during a search.
	 */
	public int getScriptsCountFromIteration(int iterationId) throws IterationSearchDAOException;

	/**
	 * Checks if an iteration is completed. In other words, checks if the
	 * related comparison matrix has been prioritized.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param iterationId the given iteration.
	 * @return true if the iteration is ended, else false.
	 * @since August, 2011.
	 * @throws IterationSearchDAOException if an error occurs during the search.
	 */
	public boolean isIterationCompleted(int iterationId) throws IterationSearchDAOException;

	/**
	 * Iteration search from a bean of criterions.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param searchBean the criterions to use for the search.
	 * @return the resulting object list.
	 * @since July, 2011.
	 * @throws IterationSearchDAOException if an error occurs during the search.
	 */
	public List<Iteration> searchIteration(IterationSearch searchBean) throws IterationSearchDAOException;

	/**
	 * Updates an iteration from his object.
	 * 
	 * @author Clement HELIOU (clement.heliou@che-software.com).
	 * @param iterationToUpdate the iteration object to update in the database.
	 * @since July, 2011.
	 * @throws IterationUpdateDAOException if an error occurs during the update.
	 */
	public void updateIteration(Iteration iterationToUpdate) throws IterationUpdateDAOException;
}